---
type: flow
title: Order Placement
description: How a cart becomes an order — the trunk every path shares, and the scenarios the system must cover.
tags: [flow]
timestamp: {{DATE}}
---
<!-- ✂ docujoint template sample — replace with your own content, then delete this comment. -->
# Order Placement

## Overview
The core buying flow. The [Buyer](</Actors/Buyer.md>) pays on the
[Checkout Page](</Apps/Storefront/Pages/Checkout Page.md>);
[Payments Service](</Services/Payments Service.md>) charges via
[Stripe](</Services/Stripe.md>); on success an
[orders](</Data/main/Tables/orders.md>) row is created with status `placed`
and [order-placed](</Events/order-placed.md>) is published.

## Map
How the concepts of this system interact along the flow — every named node is
a documented concept (actor, page, service, integration, table, event), and
the diagram is parsed like everything else: its nodes and edges land in the IR.

```mermaid
flowchart TD
  Buyer[Buyer] -->|reviews cart, opens checkout| Checkout[Checkout Page]
  Checkout -->|charge, idempotent by cart| Payments[Payments Service]
  Payments -->|payment intent| Stripe[Stripe]
  Payments -->|records every attempt| Attempts[payment_attempts]
  Stripe -->|success| Orders[orders row, status placed]
  Orders --> Event[order-placed event]
  Event -->|confirmation| Buyer
  Stripe -->|decline| Declined[Declined Payment Path]
  Declined -->|retry with new card| Payments
```

## Shared steps
Every path below goes through this trunk before branching:

1. Buyer reviews the cart and opens checkout.
2. Storefront requests a charge from the Payments Service (idempotent by cart id).
3. Payments Service calls the provider and waits for the outcome — paths diverge here.

## Features
What each step of the trunk must do, with the evidence that it does — the
flow's traceability surface, beside the Scenarios' path coverage. `step` is
the kind for a flow step; a row with only a Gap derives `missing`.

## Scenarios
All the paths this flow covers — happy, unhappy and edge — as data, with the
test that proves each. Branch documents in this folder detail the unhappy
paths, e.g. [Declined Payment Path](<Declined Payment Path.md>).

## Anomalies
A scenario whose DOCUMENTED outcome reads as a defect rather than an accepted
behaviour. This asserts nothing beyond what the scenario above already says —
and always offers "this is intended", because the judgement is the reader's.

## Open questions
Questions point at the feature they block (`About`), and ship with proposed
`Options` so a teammate answers by picking a verdict. The lifecycle: `open` →
`answered` (the knowledge arrived) → **fold the answer into the prose or a
Gap** → `archived`. q2 shows the end state; the open list stays a worklist.

## Transitions
Where an order can go from here — one row per possible move, each with the
business rule that fires it. Linked targets are nodes of the process graph;
plain-text targets converge as terminal outcomes.

| To | When |
|----|------|
| Order placed | The provider confirms the charge — the orders row is created with status `placed` and order-placed is published |
| [Declined Payment Path](<Declined Payment Path.md>) | The provider declines the charge |
| [Refund Flow](</Flows/Refund Flow/Refund Flow.md>) | A support agent confirms a refund on a placed order |